Crate rustls_pki_types

展开描述

本 crate 提供用于表示 X.509 证书、密钥及其他在 rustls 生态中常用的类型。它面向那些需要处理这些 X.509 类型的 crate，例如 rustls、rustls-webpki 等。

这些 crate 中有一些原本围绕 DER 编码字节定义了自己的简单包装类型。然而，为了避免产生不便的依赖关系，所有这些包装类型都已被解耦。通过使用一个长期 API 稳定的公共底层 crate，我们希望在避免不必要依赖关系弊病的同时，为各 crate 之间提供良好的互操作性。

§DER and PEM

本 crate 中定义的许多类型都表示 DER 编码数据。DER 是 ASN.1 格式的二进制编码，在 Web PKI 规范中被广泛使用。作为一种二进制格式，它在内存中存储时相当紧凑。但由于是二进制格式，对人类阅读以及在不便处理二进制的场景中使用并不友好。因此，许多工具和协议采用一种称为 PEM 的基于 ASCII 的 DER 编码方式。除了 base64 编码的 DER 之外，PEM 对象还通过头部和尾部行定界，标明该 PEM 数据块中所包含对象的类型。

这些类型可通过以下方式创建：

DER using (for example) PrivatePkcs8KeyDer::from().
PEM using (for example) pem::PemObject::from_pem_slice().

pem::PemObject 特性提供了从 PEM 编码构造这些类型的完整方式。包括从文件、字节切片，或从 std::io 流中读取并构造。

还提供了一个更底层的 API，可一次性完整消费给定的 PEM 文件，即使其中包含不同的数据类型：见 pem::PemObject 特性在 (pem::SectionKind, Vec<u8>) 元组上的实现。

§Creating new certificates and keys

本 crate 不提供创建新证书或密钥的功能。不过，可以使用 rcgen crate 来创建新的证书和密钥。

§Cloning private keys

本 crate 故意不为私钥类型实现 Clone，以最大程度地减少私钥数据在内存中的暴露。

若希望延长 PrivateKeyDer<'_> 的生命周期，可考虑使用 PrivateKeyDer::clone_key()。另外，由于这些类型是不可变的，也可以考虑将 PrivateKeyDer<'_> 包装在 Rc 或 Arc 中。

§Target `wasm32-unknown-unknown` with the `web` feature

std::time::SystemTime 在 wasm32-unknown-unknown 目标中不可用，因此对 UnixTime::now() 的调用——通常由 std feature 启用—— 需要改为启用 web feature 后再编译。该实现通过在浏览器中调用 Date.now() 来获取时间。

再导出§

pub use alg_id::AlgorithmIdentifier;

模块§

alg_id: The PKIX AlgorithmIdentifier type, and common values.
pem: Low-level PEM decoding APIs.

结构体§

AddrParseError: Failure to parse an IP address
CertificateDer: A DER-encoded X.509 certificate; as specified in RFC 5280
CertificateRevocationListDer: 一个证书吊销列表（CRL），如 RFC 5280 所规定
CertificateSigningRequestDer: 一个证书签名请求（CSR），如 RFC 2986 所规定
Der: DER-encoded data, either owned or borrowed
DnsName: A type which encapsulates a string (borrowed or owned) that is a syntactically valid DNS name.
EchConfigListBytes: A TLS-encoded Encrypted Client Hello (ECH) configuration list (ECHConfigList); as specified in RFC 9849 §4
InvalidDnsNameError: The provided input could not be parsed because it is not a syntactically-valid DNS Name.
InvalidSignature: A detail-less error when a signature is not valid.
Ipv4Addr: no_std implementation of std::net::Ipv4Addr.
Ipv6Addr: no_std implementation of std::net::Ipv6Addr.
PrivatePkcs1KeyDer: A DER-encoded plaintext RSA private key; as specified in PKCS#1/RFC 3447
PrivatePkcs8KeyDer: A DER-encoded plaintext private key; as specified in PKCS#8/RFC 5958
PrivateSec1KeyDer: 一个 Sec1 编码的明文私钥，如 RFC 5915 所规定
SubjectPublicKeyInfoDer: A DER-encoded SubjectPublicKeyInfo (SPKI), as specified in RFC 5280.
TrustAnchor: A trust anchor (a.k.a. root CA)
UnixTime: A timestamp, tracking the number of non-leap seconds since the Unix epoch.

枚举§

FipsStatus: FIPS validation status of an algorithm or implementation.
IpAddr: no_std implementation of std::net::IpAddr.
PrivateKeyDer: A DER-encoded X.509 private key, in one of several formats
ServerName: Encodes ways a client can know the expected name of the server.

特性§

SignatureVerificationAlgorithm: An abstract signature verification algorithm.

类型别名§

SubjectPublicKeyInfoDeprecated: A DER-encoded SubjectPublicKeyInfo (SPKI), as specified in RFC 5280.